Typical HAL AES use cases for migration

This section provides typical HAL AES use cases to help migrate from HAL1 CRYP to HAL2 AES.

Use case: encryption/decryption in polling mode

Sequence diagram

Encryption/decryption in polling mode

@startuml participant "Application" as App participant "CRYP" as CRYP note over App,CRYP: Encryption App -> CRYP: HAL_CRYP_Encrypt() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group note over App,CRYP: Decryption App -> CRYP: HAL_CRYP_Decrypt() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group @enduml

Code snippet

HAL1

HAL2 

/* Encryption */
HAL_CRYP_Encrypt(&hcryp, Plaintext, PLAINTEXT_SIZE,
                 EncryptedText, TIMEOUT_VALUE);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Decryption */
HAL_CRYP_Decrypt(&hcryp,Ciphertext , PLAINTEXT_SIZE,
                 DecryptedText, TIMEOUT_VALUE);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Encryption */
HAL_AES_Encrypt(&haes, Plaintext, PLAINTEXT_SIZE ,
               EncryptedText, TIMEOUT_VALUE);

/* Only for GCM algorithm */
HAL_AES_GCM_GenerateAuthTAG(&haes,TAG,
                             TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_AES_CCM_GenerateAuthTAG(&haes,TAG,
                             TIMEOUT_VALUE);

/* Decryption */
HAL_AES_Decrypt(&haes, Ciphertext, PLAINTEXT_SIZE ,
                DecryptedText, TIMEOUT_VALUE);

/* Only for GCM algorithm */
HAL_AES_GCM_GenerateAuthTAG(&haes,TAG,
                              TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_AES_CCM_GenerateAuthTAG(&haes,TAG,
                             TIMEOUT_VALUE);

Key changes

  1. Encryption and decryption APIs are renamed from HAL_CRYP_* to HAL_AES_*.

  2. Authentication tag generation APIs are renamed from HAL_CRYPEx_AES* to HAL_AES_* for GCM and CCM algorithms.

Use case: encryption/decryption in interrupt mode

Sequence diagram

Encryption/decryption in interrupt mode

@startuml participant "Application" as App participant "CRYP" as CRYP note over App,CRYP: Encryption App -> CRYP: HAL_CRYP_Encrypt_IT() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group note over App,CRYP: Decryption App -> CRYP: HAL_CRYP_Decrypt_IT() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group @enduml

Code snippet

HAL1

HAL2 

/* Encryption */
HAL_CRYP_Encrypt_IT(&hcryp, Plaintext, PLAINTEXT_SIZE,
                 EncryptedText);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Decryption */
HAL_CRYP_Decrypt_IT(&hcryp,Ciphertext , PLAINTEXT_SIZE,
                 DecryptedText);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Encryption */
HAL_AES_Encrypt_IT(&haes, Plaintext, PLAINTEXT_SIZE,
                               EncryptedText);

/* Only for GCM algorithm */
HAL_AES_GCM_GenerateAuthTAG(&haes,TAG,
                              TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_AES_CCM_GenerateAuthTAG(&haes,TAG,
                             TIMEOUT_VALUE);

/* Decryption */
HAL_AES_Decrypt_IT(&haes, Ciphertext, PLAINTEXT_SIZE,
                                        DecryptedText);

/* Only for GCM algorithm */
HAL_AES_GCM_GenerateAuthTAG(&haes,TAG,
                              TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_AES_CCM_GenerateAuthTAG(&haes,TAG,
                             TIMEOUT_VALUE);

Key changes

  1. Interrupt-mode APIs are renamed from HAL_CRYP_*_IT to HAL_AES_*_IT.

  2. Tag generation APIs are renamed to HAL_AES_GCM_GenerateAuthTAG() and HAL_AES_CCM_GenerateAuthTAG().

Related examples in HAL2

Example name

Brief

example_hal_cryp_cipher_aes_cbc_it

How to use the CRYP peripheral to encrypt/decrypt data (plaintext/ciphertext) in interrupt mode using AES CBC.

Use case: encryption/decryption in DMA mode

Sequence diagram

Encryption/decryption in DMA mode

@startuml participant "Application" as App participant "CRYP" as CRYP note over App,CRYP: Encryption App -> CRYP: HAL_CRYP_Encrypt_DMA() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group note over App,CRYP: Decryption App -> CRYP: HAL_CRYP_Decrypt_DMA() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group @enduml

Code snippet

HAL1

HAL2 

/* Encryption */
HAL_CRYP_Encrypt_DMA(&hcryp, Plaintext, PLAINTEXT_SIZE,
                 EncryptedText);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Decryption */
HAL_CRYP_Decrypt_DMA(&hcryp,Ciphertext , PLAINTEXT_SIZE,
                 DecryptedText);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                TIMEOUT_VALUE);

/* Encryption */
HAL_AES_Encrypt_DMA(&haes, Plaintext, PLAINTEXT_SIZE ,
                                       EncryptedText);

/* Only for GCM algorithm */
HAL_AES_GCM_GenerateAuthTAG(&haes,TAG,
                              TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_AES_CCM_GenerateAuthTAG(&haes,TAG,
                             TIMEOUT_VALUE);

/* Decryption */
HAL_AES_Decrypt_DMA(&haes, Ciphertext, PLAINTEXT_SIZE ,
                                        DecryptedText);

/* Only for GCM algorithm */
HAL_AES_GCM_GenerateAuthTAG(&haes,TAG,
                              TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_AES_CCM_GenerateAuthTAG(&haes,TAG,
                             TIMEOUT_VALUE);

Key changes

  1. DMA-mode APIs are renamed from HAL_CRYP_*_DMA to HAL_AES_*_DMA.

  2. Tag generation APIs are renamed from HAL_CRYPEx_AES* to HAL_AES_* for GCM and CCM algorithms.

Related examples in HAL2

Example name

Brief

example_hal_cryp_cipher_aes_cbc_dma

How to use the CRYP peripheral to encrypt/decrypt data (plaintext/ciphertext) using the AES CBC algorithm in DMA mode with swapping.

Use case: suspend/resume mode

Sequence diagram

Suspend/resume mode

@startuml participant "Application" as App participant "CRYP" as CRYP note over App,CRYP: CRYP initialization App -> CRYP: HAL_CRYP_Init() note over App,CRYP: Low priority block Encryption App -> CRYP: HAL_CRYP_Encrypt_IT() note over App,CRYP: Low priority process suspending App -> CRYP: HAL_CRYP_ProcessSuspend() App -> CRYP: HAL_CRYP_Suspend() note over App,CRYP: High priority process starting App -> CRYP: HAL_CRYP_Init() note over App,CRYP: Decrypt high priority block App -> CRYP: HAL_CRYP_Decrypt_IT() note over App,CRYP: Resume low priority block processing App -> CRYP: HAL_CRYP_Resume() @enduml

Code snippet

HAL1

HAL2

Thread 1

Thread 2 

/* Set the CRYP parameters */
hcryp.Instance = AES;

/* Set the CRYP parameters */
hcryp.Init.DataType = CRYP_BYTE_SWAP;
hcryp.Init.KeySize = CRYP_KEYSIZE_128B;
hcryp.Init.pKey     = AESKey128;
hcryp.Init.Algorithm = CRYP_AES_ECB;
HAL_CRYP_Init(&hcryp);

/* Low prio block Encryption */
HAL_CRYP_Encrypt_IT(&hcryp, Plaintext_8, 128, Encryptedtext);


/* request suspension */
HAL_CRYP_ProcessSuspend(&hcryp);


/* Suspend low prio block processing */
HAL_CRYP_Suspend(&hcryp);

/* -- Thread 1 released the AES peripheral and informed Thread 2 ---> */
















/* Resume low prio block processing */
HAL_CRYP_Resume(&hcryp);

/*  */








/* <--- Thread 2 asks to use the AES peripheral for a high-priority task -- */








/*  High priority block processing  */
/* Set the CRYP parameters */
hcryp.Init.DataType  = CRYP_BIT_SWAP;
hcryp.Init.KeySize   = CRYP_KEYSIZE_256B;
hcryp.Init.pKey      = AESKey256;
hcryp.Init.pInitVect = AESIV;
hcryp.Init.Algorithm = CRYP_AES_CTR;
HAL_CRYP_Init(&hcryp);

/*  Decrypt */
HAL_CRYP_Decrypt_IT(&hcryp, CiphertextAESCTR256_HighPrio,
                                16, Decryptedtext_HighPrio);

/* <--- Thread 1 releases the AES peripheral so that the low-priority task can resume -- */

Thread 1

Thread 2 

 /* Set the AES parameters */
 HAL_AES_Init(&haes,HAL_AES);
 HAL_AES_ECB_SetConfig(&haes);
 HAL_AES_SetDataSwapping(&haes, HAL_AES_DATA_SWAPPING_BYTE);
 HAL_AES_SetNormalKey(&haes, HAL_AES_KEY_SIZE_128BIT, AESKey128);

 /* Low prio block Encryption */
 HAL_AES_Encrypt_IT(&haes, Plaintext_8, 128 , Encryptedtext);


 /* request suspension */
 HAL_AES_RequestSuspend(&haes);

/* --------------------- Wait for suspend callback -------------------*/

 /* Suspend low prio block processing */
 HAL_AES_SaveContext(&haes,&p_context);

 /* -- Thread 1 released the AES peripheral and informed Thread 2 ---> */
















 /* Restore process1 context */
 HAL_AES_RestoreContext(&haes, &p_context);

 /* Resume low prio block processing */
 HAL_AES_Resume(&haes);

/*  */








/* <--- Thread 2 asks to use the AES peripheral for a high-priority task -- */








/*  High priority block processing  */
/* Set the CRYP parameters */
HAL_AES_CTR_SetConfig(&haes,AESIV);
HAL_AES_SetDataSwapping(&haes, HAL_AES_DATA_SWAPPING_BIT);
HAL_AES_SetNormalKey(&haes, HAL_AES_KEY_SIZE_256BIT, AESKey256);



/*  Decrypt */
HAL_AES_Decrypt_IT(&haes, CiphertextAESCTR256_HighPrio,
                             16, Decryptedtext_HighPrio);

/* --------------------- Wait for decrypt complete callback -------------------*/


/* <--- Thread 1 releases the AES peripheral so that the low-priority task can resume -- */

Key changes

  1. HAL2 provides explicit suspend and context management APIs: HAL_AES_RequestSuspend(), HAL_AES_SaveContext(), and HAL_AES_RestoreContext().

  2. HAL2 splits configuration steps into dedicated functions (for example, HAL_AES_ECB_SetConfig() and HAL_AES_SetNormalKey()).